Multi-axis Shapes #7666

alexshoe · 2025-12-04T22:05:01Z

Description:

Extends xref and yref to accept arrays, allowing shapes to span multiple subplots with each vertex anchored to a different axis. See #7151 for more information.

Example:

shapes: [{  
  type: 'rect',  
  x0: 0, 
  x1: 1, 
  y0: 0, 
  y1: 1,  
  xref: ['x', 'x2'],  // x0 uses 'x', x1 uses 'x2'  
  yref: ['y', 'y2']   // y0 uses 'y', y1 uses 'y2'
}]

Progress:

Step 1: Attributes & validation
- Extend xref and yref to allow array values
- Add helper function to check number of defining coordinates of a shape
- Update value validation to work with array values
Step 2: Refactor coordinate conversion
Step 3: Update shape rendering
Step 4: Addressing editable shapes
Step 5: Tests + documentation

src/components/shapes/helpers.js

src/plots/cartesian/axes.js

src/components/shapes/defaults.js

src/components/shapes/helpers.js

src/plots/cartesian/axes.js

src/components/shapes/attributes.js

src/components/shapes/constants.js

Co-authored-by: Alex Johnson <alex@plot.ly>

src/components/shapes/calc_autorange.js

src/components/shapes/defaults.js

src/components/shapes/draw.js

src/components/shapes/helpers.js

src/plots/cartesian/axes.js

src/components/shapes/attributes.js

test/jasmine/tests/shapes_test.js

emilykl · 2026-01-23T15:12:56Z

test/image/mocks/multi_axis_shapes.json

@alexshoe Could you add a label to each of these shapes to make sure everything works as expected?

emilykl · 2026-01-23T15:16:40Z

@alexshoe This is looking really good. 🎉

I left some minor comments on the implementation (mostly style and readability) and also noticed some issues with the Jasmine tests. Could you do a pass through all the Jasmine tests and make sure they make sense, are testing the right things, etc.

I also realized there's a pretty good chance that shape.label.texttemplate won't play nice with this feature at all. I would expect variables x0, x1, y0, y1 to work as expected, but the remaining ones simply don't make any sense when the endpoints are associated with different axes. Can you test out what happens? There should be a decent error case (ignore the variable, perhaps?) rather than a catastrophic failure or showing the wrong information.

alexshoe · 2026-01-26T17:50:15Z

@emilykl Thanks for the comments! I tested texttemplate with multi-axis shapes and it doesn't cause an error but the derived values (e.g. width, height, slope, et.c) don't make any sense as you predicted. Raw values (x0, x1, y0, y1) work fine but something like width would be meaningless since we're mixing coordinates from different axes. Should I document this limitation somewhere or maybe throw an error?

Meanwhile, I also modified the code to display labels for non-path shapes since it previously didn't work well with multi-axis references. Also added labels to the image test to confirm that it works.

emilykl · 2026-01-26T18:14:27Z

@alexshoe Thanks to @camdecoster 's work in #7577 , we now have the shape.texttemplatefallback attribute, which is already used in cases where the given variable name is invalid. So I propose we use texttemplatefallback for the derived variables for multi-axis shapes. See the text_on_shapes_texttemplate mock for an example of how this works in practice (%{length} on the rectangle in the upper-right subplot is replaced with - because length is an invalid variable for rectangles).

Good news that raw values work as expected!

emilykl · 2026-01-26T18:38:22Z

test/jasmine/tests/shapes_test.js

+    beforeEach(function() { gd = createGraphDiv(); });
+    afterEach(destroyGraphDiv);
+
+    function getShape(index) {


Suggested change

function getShape(index) {

function getShapesWithIndex(index) {

emilykl · 2026-01-26T20:29:04Z

test/jasmine/tests/shapes_test.js

-            expect(lineBBox.left).toBeCloseTo(lineExpectedLeft);
-            expect(lineBBox.right).toBeCloseTo(lineExpectedRight);
+            var lineBBox = getBoundingBox(0);
+            expect(lineBBox.left).toBeCloseTo(xa.l2p(1) + xa._offset);


My only issue with this testing approach is the question of whether xa._offset itself might ever have an incorrect value due to the presence of a multi-axis shape. Do you know where/how xa._offset is calculated?

If you think that's not possible, this is OK.

emilykl · 2026-01-26T20:29:22Z

test/jasmine/tests/shapes_test.js

+            expect(gd._fullLayout.xaxis2.range[0]).toBeLessThan(1);
+            expect(gd._fullLayout.xaxis2.range[1]).toBeGreaterThan(5);
+            expect(gd._fullLayout.yaxis2.range[0]).toBeLessThan(1);
+            expect(gd._fullLayout.yaxis2.range[1]).toBeGreaterThan(5);


Should probably use .toBeCloseTo() here as well

alexshoe added 3 commits December 2, 2025 14:02

Extend xref and yref attributes

c8be45f

Add function to help validate number of defining shape vertices

a7b3bb2

Update shape defaults to handle an array of references

ace820b

alexshoe assigned emilykl Dec 4, 2025

emilykl reviewed Dec 4, 2025

View reviewed changes

src/components/shapes/helpers.js Outdated Show resolved Hide resolved

alexshoe marked this pull request as draft December 4, 2025 22:16

emilykl reviewed Dec 4, 2025

View reviewed changes

src/components/shapes/helpers.js Outdated Show resolved Hide resolved

emilykl reviewed Dec 4, 2025

View reviewed changes

src/plots/cartesian/axes.js Outdated Show resolved Hide resolved

emilykl reviewed Dec 4, 2025

View reviewed changes

src/plots/cartesian/axes.js Show resolved Hide resolved

emilykl reviewed Dec 4, 2025

View reviewed changes

src/plots/cartesian/axes.js Outdated Show resolved Hide resolved

emilykl reviewed Dec 4, 2025

View reviewed changes

src/plots/cartesian/axes.js Show resolved Hide resolved

emilykl reviewed Dec 4, 2025

View reviewed changes

src/plots/cartesian/axes.js Show resolved Hide resolved

Modify shape xref/yref coercion logic

a910d42

camdecoster reviewed Dec 8, 2025

View reviewed changes

Refactor coercion logic

4d70fd3

ndrezn assigned alexshoe Dec 10, 2025

alexshoe added 7 commits December 17, 2025 11:59

Implement coordinate value coercion for array refs

d3208e9

Refactor clip path calculation for multi-axis shapes

e5a71ad

Merge branch 'master' into multi-axis-reference-shapes

4a571aa

Refactor autorange calculation for multi-axis shapes

5f7eedf

update plot-schema diff

777cded

Add image test and generated baseline for multi-axis shapes

0a5093f

Add Jasmine tests for multi-axis shapes

de1e72c

alexshoe marked this pull request as ready for review January 1, 2026 19:17

alexshoe requested a review from emilykl January 1, 2026 19:17

Upload correct image baselines from CI run

e089cdf

alexcjohnson reviewed Jan 5, 2026

View reviewed changes

src/components/shapes/attributes.js Outdated Show resolved Hide resolved

alexcjohnson reviewed Jan 5, 2026

View reviewed changes

src/components/shapes/constants.js Outdated Show resolved Hide resolved

alexshoe and others added 2 commits January 6, 2026 12:09

Update src/components/shapes/constants.js

be959e9

Co-authored-by: Alex Johnson <alex@plot.ly>

Merge branch 'plotly:master' into multi-axis-reference-shapes

ef94099

emilykl reviewed Jan 14, 2026

View reviewed changes

src/components/shapes/calc_autorange.js Outdated Show resolved Hide resolved

emilykl reviewed Jan 14, 2026

View reviewed changes

src/components/shapes/calc_autorange.js Outdated Show resolved Hide resolved

alexshoe added 4 commits January 15, 2026 16:11

Add more detail to attribute descriptions

8489819

Count defining coordinates by axis

b2a246f

Refactor calcArrayRefAutorange as pure function

3262220

Normalize axis references in coerceRefArray using cleanId

296bd55

emilykl reviewed Jan 21, 2026

View reviewed changes

src/components/shapes/calc_autorange.js Show resolved Hide resolved